home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 February / EnigmA AMIGA RUN 15 (1997)(G.R. Edizioni)(IT)[!][issue 1997-02][PLANET CD V].iso / enigma / earcd / utility / utilfile / rw2ent16.lha / Raw2Ent.doc < prev    next >
Text File  |  1996-12-06  |  16KB  |  498 lines
  1. Project: Raw2Ent
  2. ARexx  : Raw2Ent.rexx
  3. Version: 1.4.1 (14.07.96)
  4. Program: Raw2Ent
  5. Version: 1.6 (06.12.96)
  6. Author : Tamio Patrick Honma
  7.  
  8. Files  : CWISENV
  9.          Raw2Ent
  10.          Raw2Ent.doc
  11.          Raw2Ent.rexx
  12.          Raw2Ent.rexx.old
  13.  
  14.  
  15.  
  16. CONTENTS:
  17.  
  18. 1. INTRODUCTION
  19. 1.1. REQUIREMENTS
  20.  
  21. 2. USAGE
  22. 2.1. Raw2Ent VER: 1.6 (06.12.96)
  23. 2.2. Raw2Ent.rexx VER: 1.4.1 (14.07.96)
  24. 2.3. CWISENV
  25. 2.4. ARGUMENT-PRIORITY
  26.  
  27. 3. LIMITATIONS
  28.  
  29. 4. INSTALLATION
  30.  
  31. 5. EXAMPLES
  32.  
  33. 6. BYE!
  34.  
  35. 7. LAST COMMENT
  36.  
  37. 8. BUG REPORTS
  38.  
  39. 9. HISTORY
  40.  
  41. 10.SUPPORT & MS-DOS-VERSION
  42.  
  43.  
  44.  
  45.  
  46. 1. INTRODUCTION
  47.  
  48. Raw2Ent   converts   raw   8-Bit-ASCII-Text   into   7-Bit-ASCII-Text   with
  49. entity-codes  and  reverse.   The  ASCII-Format is a standardized format for
  50. information  interchange,  but it is only standardized seven-bit-wide, which
  51. means  that  128 codes are defined.  One Byte consists of eight bits and can
  52. represent  256  different  bit  combinations.   Therefore  the  last 128 bit
  53. combinations  are defined for free use by any operation-system.  The problem
  54. is that accent-characters and other special characters are not standardized,
  55. because  they  are defined in (guess where?!  ;) ) the free part of ASCII by
  56. the operation system developers.
  57.  
  58. The  goal of the Wold Wide Web developers was that it could be used on every
  59. important   operation   system.   So  it  was  clear  that  the  ASCII-Based
  60. HTML-Source-Code   had  to  use  the  standardized  seven-bit  area  of  the
  61. ASCII-Code.  To represent accent-characters or other special characters in a
  62. seven-bit-code,  it  was  neccesary  to  invent something.  And this was the
  63. entity-code  -  a  kind  of  escape-code.   An  entity-code  consists  of an
  64. introducing  "&"  and  a  ";"  at  the  end.   Between  these  symbols  is a
  65. character-name the browser can interpret.  It is a very hard and stupid work
  66. to convert the ASCII-Text by hand.  So just use Raw2Ent!
  67.  
  68. Raw2Ent  produces  real 7-Bit-ASCII-Code.  All printable Amiga-characters in
  69. the  8-bit-area  will be converted into entity-codes, without any exception.
  70. The  use  of names instead of code-numbers will make the entity-codes easier
  71. to be read by humans.
  72.  
  73. You  can use Raw2Ent also to check, wether your file contains pure seven-bit
  74. codes  or  not.   If  not,  Raw2Ent  will  present  you  the position of the
  75. 8-Bit-Characters in the text.
  76.  
  77.  
  78. 1.1. REQUIREMENTS
  79.  
  80. - AmigaOS 2.0 or greater
  81. - optional: ARexx
  82.  
  83.  
  84.  
  85. 2. USAGE
  86.  
  87. Raw2Ent  consists  of  three parts:  one assembler-program, one ARexx-Script
  88. and one Batch-File.
  89.  
  90. If   you   just   want   to   convert   a  text  once,  you  just  need  the
  91. assembler-program.   If  you  want  to  convert  one text more than one time
  92. because  you work on a project, like a web-page with actual information, the
  93. ARexx-Script may be useful.
  94.  
  95.  
  96.  
  97. 2.1. Raw2Ent VER: 1.6 (06.12.96)
  98.  
  99. arguments:
  100.  
  101.   FROM              - The source-file (eight bit wide)
  102.   TO                - The destination-file (with entity-codes)
  103.                       [path without filename is not accepted]
  104.   TAG/S             - activates the TAG-Mode
  105.   HTML/S            - activates the HTML-Mode
  106.   ENT/S             - default mode
  107.   UML=NOENT/S       - removes high-bit characters by characters or words
  108.   CODE/S            - converts all entity-codes by code-number
  109.                       (except the four special entities)
  110.   TOTALCODE/S       - converts ALL characters by entity-code-numbers
  111.   SMART/S           - activates the smart-mode
  112.   INVERSE=ENT2RAW/S - inverses the function of Raw2Ent to Ent2Raw
  113.   CHECK/S           - checks, if your Text is pure 7-Bit-ASCII
  114.  
  115.  
  116. modes:
  117.  
  118.  
  119. >TAG-Mode<
  120.  
  121. will  not  convert  the  four  characters:   &  <  > ".  This is usefull for
  122. ASCII-Text  which  already  contains  entity-codes  or  HTML-TAGS, which are
  123. introduced  and  ended  by  "<"  and  ">" and which can contain quotes.  The
  124. "&"-character  usually introduces the entity-codes.  If you use the TAG-Mode
  125. the entity-codes in the source-file will not be converted a second time in a
  126. wrong  way,  but  untouched special-characters will be converted.  Therefore
  127. you should use this mode, whenever you convert a text a second time.
  128.  
  129.  
  130. >HTML-Mode<
  131.  
  132. will  just  copy  the  source-file to the destination-file.  This feature is
  133. implemented  to  make the program be easier used in script-files.  (see i.e.
  134. Raw2Ent.rexx)
  135.  
  136.  
  137. >ENT-Mode<
  138.  
  139. is the default mode and converts every known character into its entity-code.
  140.  
  141.  
  142. >NOENT-Mode< or >UML-Mode<
  143.  
  144. is  a  mode,  which  replaces  each  high-bit character by characters in the
  145. low-bit  area  without  using  character-entity-codes.   I.e.:   "ü" will be
  146. converted  to  "ue"  and  "£"  will  be converted to "pound" and "©" will be
  147. converted  to  "(C)"  and  so on.  It is recommended to use this argument in
  148. accompany  with  the  "TAG"-argument.   Optionally  you can use >UML< (like:
  149. Umlaute),  which  is  a  synomnym  to  >NOENT<.   [This mode was inspired by
  150. Andreas Bais]
  151.  
  152.  
  153. >CODE-Mode<
  154.  
  155. will   convert  all  entity-codes  not  by  the  entity-names,  but  by  the
  156. entity-code-numbers.   This may be usefull, if a browser doesn't support all
  157. entity-names, but the numbers.  Note:  On the one hand code-numbers are hard
  158. to  be  read  by  humans,  but on the other hand the destination-file may be
  159. shorter.  [The shortest files may be converted in the "TAG NOENT"-Mode.]
  160.  
  161.  
  162. >TOTALCODE-Mode< or >TOTCODE-Mode<
  163.  
  164. will  convert EVERY character by its code-number.  The only use of this mode
  165. is to make it hard for humans to read the text-file.  This text will only be
  166. displayed  readable  by  a  HTML-Browser.  This mode will surely produce the
  167. largest destination-files!
  168.  
  169.  
  170. >SMART-Mode<
  171.  
  172. is  a  combination  of  the  >ENT<-Mode  and the >TAG<-Mode.  HTML-Files for
  173. example   will   be   converted   without   destruction   of  HTML-Tags  and
  174. character-entity-codes  -  like  the >TAG<-Mode.  The difference is that the
  175. characters:   <  >  &  "  will  be  converted, if Raw2Ent "thinks" that this
  176. characters are no elements of the character-entity-codes or HTML-Tags.  This
  177. works the best, if the HTML-File contains "good" code.  I cannot guarantee a
  178. correct  interpreatation  by  Raw2Ent,  but  I  think  it  works with 95% of
  179. HTML-Files without mistakes.
  180.  
  181.  
  182. >INVERSE-Mode< or >ENT2RAW-Mode<
  183.  
  184. converts  all character-entity-codes (names or numbers) into the Amiga-ASCII
  185. -  the  Latin-1  standard.  So you can use Raw2Ent as a Ent2Raw.  If you set
  186. the  >TAG<-Mode,  this  Mode  will not touch the codes:  > < & and
  187. ".
  188.  
  189.  
  190. >CHECK-Mode<
  191.  
  192. checks, if your text is pure 7-Bit-ASCII.  Raw2Ent will inform you about the
  193. position,  the  character  and  classification  of the 8-Bit-codes.  Raw2Ent
  194. differs  the  8-bit-characters in two ways:  those inside SGML/HTML-Comments
  195. and  those  outside  comments.   The  program will represent three different
  196. textfile-states:
  197.  
  198. the text contains pure 7-bit-ASCII                      -> $RC=0 (OK)
  199. the text contains just 8-bit-characters inside comments -> $RC=1
  200. the text contains 8-bit-characters                      -> $RC=5 (WARN)
  201.  
  202. This mode is interruptable with the break-signal CTRL+C.
  203.  
  204.  
  205.  
  206. return-codes:
  207.  
  208. $RC=0  (OK)    -> everything's fine!
  209. $RC=5  (WARN)  -> wrong usage
  210. $RC=10 (ERROR) -> error (memory)
  211. $RC=20 (FAIL)  -> failure (input/output)
  212.  
  213.  
  214. 2.2. Raw2Ent.rexx VER: 1.4.1 (14.07.96)
  215.  
  216. arguments:
  217.  
  218.   FROM/A            - The source-file (eight bit wide)
  219.   TO/A              - The destination-file (with entity-codes)
  220.                       [path without filename is not accepted]
  221.   TAG/S             - activates the TAG-Mode
  222.   HTML/S            - activates the HTML-Mode
  223.   ENT/S             - default mode
  224.  
  225.  
  226. modes:
  227.  
  228.   see Raw2Ent-Usage (2.1.)
  229.  
  230.  
  231. Raw2Ent.rexx manages:
  232.  
  233.   - destination-path without filename
  234.   - suffix-handling (destinationfile has the suffix ".ent")
  235.   - progress-display
  236.   - enviroment-variables for automation without mistakes
  237.  
  238.  
  239.  
  240. 2.3. CWISENV
  241.  
  242. Use  CWISENV  to  set  the  enviroment-variables for a specific file, if you
  243. don't want to use the Raw2Ent.rexx-arguments - i.e. in batch-files.
  244.  
  245. arguments:
  246.  
  247. FILENAME/A  -  is  the filename of the input-file for Raw2Ent.  NOTE:  Don't
  248.                use  pathnames!  You must use the "cd"-command with the
  249.                pathname, where your textfile (input) can be found.
  250.  
  251. MODE/A      -  selects the Mode. You can choose: ENT, TAG, HTML
  252.  
  253. modes:
  254.  
  255.   see Raw2Ent-Usage (2.1.)
  256.  
  257.  
  258.  
  259. 2.4. ARGUMENT-PRIORITY
  260.  
  261. highest priority  FROM        -  all modes usable
  262.        ^          TO          -  all modes usable except "CHECK"
  263.        |
  264.        |          CHECK/S     -  disables ALL other switches
  265.        |          INVERSE/S   -  disables ALL other switches except "TAG"
  266.        |          HTML/S      -  disables ALL the rest of the switches
  267.        |          TOTALCODE/S -  disables ALL the rest of the switches
  268.        |          CODE/S      -  disables the switches: "NOENT" and "ENT"
  269.        |          NOENT/S     -  disables the switches: "ENT" and "SMART"
  270.        |          TAG/S       -  disables the switches: "ENT" and "SMART"
  271.        v          SMART/S     -  disables the switch  : "ENT"
  272. lowest priority   ENT/S       -  doesn't affect other switches
  273.  
  274.  
  275.  
  276. 3. LIMITATIONS
  277.  
  278.   - A text can only be converted in one part. No markup possible.
  279.   - The enviroment-variables have no information about paths.
  280.     So i.e. all "index.html"-files have the same variable.
  281.     The variables are ignored, if you set the "TAG"- or "HTML"- or "ENT"-Switch
  282.     on your own. Please note that only the ARexx-Script supports variables -
  283.     NOT the assembler-program!
  284.   - No convertion-progress-display implemented. If you want to have this, you
  285.     can use the old ARexx-Script Raw2Ent.rexx v1.3.
  286.   - The old ARexx-Script [1.3] is not compatible to the assembler program.
  287.   - Raw2Ent cannot be stopped by the break signals.
  288.   - Raw2Ent just supports the Amiga-8-Bit-ASCII [ISO-8859-1], but this is okay
  289.     because there are many ways to convert texts from PC, Mac, Unix and other
  290.     systems:
  291.     - Use the CrossDOS-Commodity. (This is the best way - because every
  292.       AmigaOS 2.1+ User has this program in the Tools/Commodities-directory!)
  293.     - There are many converters in AmiNet or other Freeware-Sources. I.e.:
  294.       - "CharConv" by Johan Billing [v1.6 from 1994]
  295.   - If you search for a good HTML to TXT converter, then try this one:
  296.     - "HTTX" by Gabriele Favrin [v1.0 from 1996]
  297.  
  298.  
  299. 4. INSTALLATION
  300.  
  301. 4.1. Copy "Raw2Ent" and "Raw2Ent.rexx" into the same directory.
  302.  
  303. 4.2. Change the path-name in the "Raw2Ent.rexx"-Script.
  304.  
  305. 4.3. makedir ENVARC:cwis/
  306.  
  307.  
  308.  
  309. 5. EXAMPLES
  310.  
  311.  
  312. 5.1. "Raw2Ent Text.html Text.ent TAG"
  313.  
  314. Converts  the  file  "Text.html"  into  the  file "Text.ent" by entity-codes
  315. without destruction of HTML-Tags and already converted Entity-Codes.
  316.  
  317.  
  318.  
  319. 5.2. "Raw2Ent Text Text.ent" or
  320.      "Raw2Ent Text Text.ent ENT"
  321.  
  322. Converts the file "Text" into "Text.ent" without having regard for HTML-Tags
  323. or already converted Entity-Codes.
  324.  
  325.  
  326.  
  327. 5.3. "Raw2Ent Text.html Text.ent HTML"
  328.  
  329. Just copies the file "Text.html" to "Text.ent".
  330.  
  331.  
  332.  
  333. 5.4. "Raw2Ent Text.html Text.ent TAG CODE"
  334.  
  335. Same  as  example  5.1. but  all  character-entity-codes  are represented by
  336. code-numbers and no code-names.
  337.  
  338.  
  339.  
  340. 5.5. "Raw2Ent Text Text.ent CODE"
  341.  
  342. Same  as  example  5.2. but  all  character-entity-codes  are represented by
  343. code-numbers,  except  the  four  characters:   <  >  "  ?,  which are still
  344. represented by their character-entity-names.
  345.  
  346.  
  347.  
  348. 5.6. "Raw2Ent Text Text.uml TAG NOENT" or
  349.      "Raw2Ent Text Text.uml TAG UML"
  350.  
  351. This  will  convert  raw  text  into  seven-bit-wide-text without the use of
  352. character-entity-codes.   Raw2Ent  will  convert  the  text with alternative
  353. characters or words or shortcuts.  The destination-file in this example will
  354. contain  not  a  single  character-entity-code,  because  of  the use of the
  355. >TAG<-argument.
  356.  
  357.  
  358. 5.7. "Raw2Ent Text Text.code TOTALCODE"
  359.  
  360. The  file  "Text.code"  will  contain just code-number-entities, without any
  361. exception.  The destination file will be very large! Note: The TAG-Mode will
  362. be ignored, if you use this mode. Therefore you will not be able to use this
  363. mode for HTML-Files, but you can only read this file with a HTML-Browser.
  364.  
  365.  
  366. 5.8. "Raw2Ent Text.ent Text INVERSE" or
  367.      "Raw2Ent Text.ent Text ENT2RAW"
  368.  
  369. This will convert the file "Text.ent" to the Amiga-ASCII-File "Text".
  370.  
  371.  
  372. 5.9. "Raw2Ent Text.ent Text TAG INVERSE" or
  373.      "Raw2Ent Text.ent Text TAG ENT2RAW"
  374.  
  375. This  is  the  same  as 5.8..  The only difference is, that the codes:  >
  376. < & and "e; will not be converted.
  377.  
  378.  
  379. 5.10."Raw2Ent Text CHECK"
  380.  
  381. Checks the file "Text" for 7-Bit-ASCII.
  382.  
  383.  
  384.  
  385. 6. BYE!
  386.  
  387. ----------------------------------------------------------------------------
  388.        THE AUTHOR IS NOT RESPONSIBLE FOR ANY LOSS OF DATA OR DAMAGE!
  389.  
  390.                 USE THIS FREEWARE-PROGRAM ON YOUR OWN RISK.
  391. ----------------------------------------------------------------------------
  392.  
  393. Send comments to:
  394.  
  395. Tamio Patrick Honma
  396.  
  397. eMail: honma@thepentagon.com
  398.   WWW: http://www.netforward.com/thepentagon/?honma
  399.  
  400.  
  401. P.S. This program was made for the CWIS-Script-System on Amiga and PC.
  402.      The CWIS of the Heinrich-Heine-Universität Düsseldorf can be found here:
  403.  
  404.      http://www.phil-fak.uni-duesseldorf.de/cwis/
  405.  
  406.  
  407.  
  408.  
  409. 7. LAST COMMENT:
  410.  
  411. Hey!?    What   do  you  want!?   I'm  just  a  sociology-,  education-  and
  412. information-science-student and no programmer-student!
  413.  
  414. Just send me your bug-reports, ... ;)
  415.  
  416.  
  417.  
  418. ---> Raw2Ent-Assembler-Program <---
  419.  
  420. 8. BUG REPORTS:
  421.  
  422. Reported by        Bug                                          fixed Version
  423.  
  424. Joakim Andersson   Entity-Codes Å and å missing     1.0.1 (04.09.96)
  425.  
  426. Tamio Honma        Last Byte in destination-file has been       1.1 (05.09.96)
  427.                    deleted
  428.  
  429. Tamio Honma        Version-String missed one space-char         1.1.1 (06.09.96)
  430.  
  431. Marcus Beranek     Entity-Codes to ÿ,ï,Ï,æ,Æ,ø,Ø,ë,Ë missing    1.1.3 (06.09.96)
  432.  
  433. Tamio Honma        Mistake in circumflex-accents                1.1.4 (08.09.96)
  434.  
  435.  
  436. 9. HISTORY:
  437.  
  438. Version  Feature                                                Date
  439.  
  440. 1.0      first release                                          13.07.06 (*)
  441.  
  442. 1.1      Improved the speed approx 20 (!!!) times!              05.09.96
  443.          Version-String added
  444.  
  445. 1.1.2    Optimised code (speed increased)                       06.09.96
  446.          Return-Codes added (see paragraph 2.1 for return-codes)
  447.  
  448. 1.1.3    HTML-Tags to °,¹,²,³ added (faked)                     06.09.96
  449.  
  450. 1.1.4    All Entity-Codes available on Amiga-Charset included!  08.09.96 (*)15
  451.          Entity-Codes refering to the HTML 3.2 standard
  452.          All available names included
  453.          Codes without names represented by code-number
  454.          faking HTML-Tags removed
  455.  
  456. 1.1.5    Just changed a code-number by entity-name "§"     14.10.96
  457.  
  458. 1.1.6    changed all code-numbers to entity-names (completely!) 30.10.96
  459.  
  460. 1.2      added CODE-Mode                                        01.11.96 (*)
  461.  
  462. 1.3      added NOENT-Mode and TOTALCODE-Mode                    03.11.96 (*)
  463.          Version-String will be displayed in the usage-text
  464.  
  465. 1.4      added SMART-Mode                                    06-07.11.96 (*)
  466.  
  467. 1.5      added INVERSE-Mode for names and codes (Ent2Raw)    07-10.11.96 (*)
  468.          added HELP-Text
  469.  
  470. 1.6      added CHECK-Mode                                       06.12.96 (*)
  471.          some minor changes
  472.  
  473.  
  474. (*) = released in Aminet
  475.       number represents the number of the Aminet CD-ROM
  476.  
  477.  
  478. 10. SUPPORT & MS-DOS-VERSION
  479.  
  480. If  you want to get the newest release of Raw2Ent, then look into the Aminet
  481. or   send   an   eMail   to:    honma@thepentagon.com   with   the  subject:
  482. "+GET Raw2Ent#?"
  483.  
  484. If  you  want  to  get  the  MS-DOS-Version  of  Raw2Ent,  try this subject:
  485. "+GET TXT2ENT#?"
  486.  
  487. If  you  want  to get a description of all files available from me, try this
  488. subject:  "+GET README.txt"
  489.  
  490. Or to get a list of all files, try this subject:  "+GET LIST"
  491.  
  492. All  files  are  sent  as  MIME.   Type  "+GETUU"  if  you  want  to  get  a
  493. UUEncoded-File.
  494.  
  495.  
  496. Thanks to Juan J. García de Soria for his "YAMServ"-Script
  497. Thanks to Marcel Beck for his "YAM"-Mailer
  498.